<?php

// ------------------------------------------------------------------------
// |@Author       : Jarmin <topextend@qq.com>
// |@----------------------------------------------------------------------
// |@Date         : 2025-05-05 05:20:14
// |@----------------------------------------------------------------------
// |@LastEditTime : 2025-05-08 20:29:16
// |@----------------------------------------------------------------------
// |@LastEditors  : Jarmin <topextend@qq.com>
// |@----------------------------------------------------------------------
// |@Description  : HTTP状态码特征
// |@----------------------------------------------------------------------
// |@FilePath     : HttpStatusTrait.php
// |@----------------------------------------------------------------------
// |@Copyright (c) 2025 http://www.ladmin.cn All Rights Reserved.
// ------------------------------------------------------------------------
declare (strict_types=1);

namespace think\admin\traits;

/**
 * HTTP状态码特征
 *
 * 核心功能：
 * 1. 定义标准HTTP状态码
 * 2. 提供业务错误码到HTTP状态码的映射
 * 3. 提供状态码描述文本
 *
 * @package think\admin\traits
 * @version 1.0.0
 */
trait HttpStatusTrait
{
    // HTTP 标准状态码
    protected const HTTP_OK = 200;                // 请求成功
    protected const HTTP_CREATED = 201;           // 创建成功
    protected const HTTP_ACCEPTED = 202;          // 请求已接受，但尚未处理完成
    protected const HTTP_NO_CONTENT = 204;        // 请求成功，无返回内容
    protected const HTTP_MOVED = 301;             // 永久重定向
    protected const HTTP_FOUND = 302;             // 临时重定向
    protected const HTTP_NOT_MODIFIED = 304;      // 资源未修改
    protected const HTTP_BAD_REQUEST = 400;       // 请求参数错误
    protected const HTTP_UNAUTHORIZED = 401;      // 未授权
    protected const HTTP_FORBIDDEN = 403;         // 禁止访问
    protected const HTTP_NOT_FOUND = 404;         // 资源不存在
    protected const HTTP_METHOD_NOT_ALLOWED = 405;// 请求方法不允许
    protected const HTTP_CONFLICT = 409;          // 资源冲突
    protected const HTTP_UNPROCESSABLE = 422;     // 请求格式正确，但语义错误
    protected const HTTP_TOO_MANY_REQUESTS = 429; // 请求过于频繁
    protected const HTTP_SERVER_ERROR = 500;      // 服务器内部错误
    protected const HTTP_SERVICE_UNAVAILABLE = 503;// 服务不可用

    /**
     * 获取业务错误码对应的HTTP状态码
     *
     * @param int $code 业务错误码
     * @return int HTTP状态码
     */
    protected function getHttpStatusCode(int $code): int
    {
        // 业务错误码映射到HTTP状态码
        return match (true) {
            // 授权相关错误 (1000-1999)
            $code >= 1000 && $code < 2000 => self::HTTP_UNAUTHORIZED,

            // 业务逻辑错误 (2000-2999)
            $code >= 2000 && $code < 3000 => self::HTTP_BAD_REQUEST,

            // 第三方服务错误 (3000-3999)
            $code >= 3000 && $code < 4000 => self::HTTP_BAD_REQUEST,

            // 数据操作错误 (4000-4999)
            $code >= 4000 && $code < 5000 => self::HTTP_UNPROCESSABLE,

            // 系统级错误 (5000-5999)
            $code >= 5000 => self::HTTP_SERVER_ERROR,

            // 默认错误
            default => self::HTTP_BAD_REQUEST,
        };
    }

    /**
     * 获取HTTP状态码描述文本
     *
     * @param int $code HTTP状态码
     * @return string 状态描述
     */
    protected function getHttpStatusText(int $code): string
    {
        return match ($code) {
            self::HTTP_OK => 'OK',
            self::HTTP_CREATED => 'Created',
            self::HTTP_ACCEPTED => 'Accepted',
            self::HTTP_NO_CONTENT => 'No Content',
            self::HTTP_MOVED => 'Moved Permanently',
            self::HTTP_FOUND => 'Found',
            self::HTTP_NOT_MODIFIED => 'Not Modified',
            self::HTTP_BAD_REQUEST => 'Bad Request',
            self::HTTP_UNAUTHORIZED => 'Unauthorized',
            self::HTTP_FORBIDDEN => 'Forbidden',
            self::HTTP_NOT_FOUND => 'Not Found',
            self::HTTP_METHOD_NOT_ALLOWED => 'Method Not Allowed',
            self::HTTP_CONFLICT => 'Conflict',
            self::HTTP_UNPROCESSABLE => 'Unprocessable Entity',
            self::HTTP_TOO_MANY_REQUESTS => 'Too Many Requests',
            self::HTTP_SERVER_ERROR => 'Internal Server Error',
            self::HTTP_SERVICE_UNAVAILABLE => 'Service Unavailable',
            default => 'Unknown Status',
        };
    }
}
